The sample DataAdaptor in this example does the following:
Allows the user to load and save interview data from an SQL database
Allows the user to view cases available for loading in an SQL database
Loading and saving entities and their attributes
Loading and saving a many-many relationship
The sample code demonstrates:
Creating a custom Data Adaptor plugin that performs all the main Data Adaptor functionality of list, load, and save
How to retrieve data from the datasource and use the retrieved data to build InterviewUserData using Rulebase model data for load() method (more information in Understanding the InterviewSession)
How to use the Rulebase model and instance data to build the data to be persisted to the datasource - in this case the SQL inserts(more information in Understanding the InterviewSession)
The sample code is for requirements such as:
The user can save Interview data
The user can reload saved Interview data
The user needs to be able to select which saved Interview data to load
The Interview data needs to be saved to a datasource so, for example, other systems can use the base or inferenced data from the interview
Pre-seeding the Web Determinations Interview with data from an existing datasource (see Data Adaptor - Common Scenarios on how to initiate pre-seeded Web Determinations Interviews )
The user can manually save Interview data for progress, and load it in the future.
Setup
This sample code needs the following to run:
DerbyDataAdaptor (Data Adaptor plugin - see source below)
The Parents and Children rulebase (examples\rulebases\compiled\Parents and Children.zip)
The rule is not relevant for this sample, it is the entities, attributes, and relationships that we are interested about (since the Data Adaptor needs to save and load them)
The Rule entities it uses are: Global, child, person.
The relationships are:
source
relationship type
target
source text
target text
person
m-m
child
personschild
childsparents
The attributes relevant to this example:
Global
the sun is shining
Child
the child's name
the child is eating ice-cream
Person
the person's name
About the DERBY Database
The DERBY SQL database is created by using create_db.sql which is located in examples\interview-engine\data-adaptor\src.
The Database tables are:
WD_CASE (represents the Global entity)
WD_CASE_ID (VARCHAR(255), PK)
SUN_SHINING(INT)
CHILD
CHILD_ID (INT, PK-IDENTITY)
WD_CASE_ID (VARCHAR(255),FK)
CHILD_NAME (VARCHAR(255))
EATING_ICECREAM(INT)
PERSON
PERSON_ID (INT, PK – IDENTITY)
PERSON_NAME(VARCHAR(255))
CHILD_PARENT (represents the m:m relationship 'childsparents')
CHILD_ID (INT, PK and FK)
PARENT_ID (INT, PK and FK)
About the Derby Data Adaptor plugin
The sample plugin can do the following:
list all the Case ID's available for loading
load instance data for the 'child' entity via the Child table
load instance data for teh 'person' entity via the Person table
load relationship data between the 'child' instances and the 'person' instances
save 'child' instance data - including its attributes
save 'person' instance data - including attributes
save the relationships between the 'child' instances and the 'person' instances
All the main methods of the DerbyDataAdaptor (listCases, load and save) use the methods for connecting and disconnecting to the DERBY database (connectDBObjects, closeDBObjects). Because those methods connect to the database, they must put the method logic in a try-catch block.
To setup this scenario:
Create the SQL Database using create_db.sql which can be found in examples\interview-engine\data-adaptor\src
Copy the rulebase .zip file (Parents and Children.zip) from examples\rulebases\compiled to the rulebase folder in Web Determinations (for example, <webroot>\WEB-INF\classes\rulebases)
Copy and install the DerbyDataAdaptor.jar file (located in examples\interview-engine\data-adaptor) into Web Determinations; for more information, refer to Create a Plugin
Copy the DERBY libraries to library folder in Web Determinations (for example, <webroot>\WEB-INF\lib)
Ensure that DERBY is run in network server mode
Run a Web Determinations Interview
How the DerbyDataAdaptor works
The DerbyDataAdaptor is triggered by the following actions (detailed in the Data Adaptor Plugin page), that is:
When the user clicks on the Load, the DataAdaptor listCases() is called
When the user selects a case in the 'Load Case' screen, the DataAdaptor load() is called
If the interview is to be pre-seeded using the constructed URL, the DataAdaptor load() is called
When the user clicks Save, the Data Adaptor save() is called without going through the 'Save As' process.
Even if the session already has a Case ID associated to it, the Data Adaptor generates a new Case ID and saves the interview data to that Case ID. The Data Adaptor essentially does not save into an existing Case ID
listCases()
The listCases() method is straightforward. It needs to retrieve all the available cases that can be 'loaded'. These cases are stored in the WD_CASE table, so this method simply queries the WD_CASE table, retrieves all the ID's, and returns them to be displayed in the 'Load' screen.
load()
The load() method builds the InterviewUserData to be returned with the following steps:
The user is authenticated
The method connects to the database
Creates a new interview user data
Retrieves the global record in WD_CASE table by using the case ID
Gets the global interview entity instance in the created interview user data
Sets the attribute ‘sun_shining’ in the global instance
Retrieves all children from the CHILD table by using the case ID
For each child retrieved in step 7;
An interview entity instance is created for the child
The ‘child_name’ and ‘eating_icecream’ are set in the child’s interview entity instance.
The child’s interview entity instance containment parent is set to the global interview entity instance.
The global interview entity instance containment for child entity is set to complete.
Retrieves all people from the CHILD table by using the case ID
For each person retrieved in step 10;
An interview entity instance is created for the person
The ‘person_name’ attribute is set in the person’s interview entity instance.
The person’s entity instance containment parent is set to global interview entity instance.
The global interview entity instance containment for person entity is set to complete.
For each person interview entity instance created in step 11, the relationship ‘personschildren’ is set by adding the appropriate child interview entity instance/s using the table CHILD_PARENT.
The database objects are closed and connection is terminated.
save()
The save() method accesses the Rulebase model data (Rulebase object) and the Session instance data (Session object) to save the current Interview user data. For this sample code, the global, child and person entities’ instances are saved.
Only base attributes for all entities are saved.
The save process is as follows:
The user is authenticated
The method connects to the database
The global entity instance from the session is written in the WD_CASE table with fields WD_CASE_ID and SUN_SHINING .
For each contained child entity instance in the global entity instance, the child entity instance is written in the CHILD table with fields WD_CASE_ID, CHILD_NAME and EATING_ICECREAM. Note: When a record is written in the CHILD table, the CHILD_ID is automatically generated.
For each contained person entity instance in the global entity instance, the person entity instance is written in the PERSON table with fields WD_CASE_ID and PERSON_NAME Note: When a record is written in the PERSON table, the PERSON_ID is automatically generated.
The m:m relationship ‘parentschildren’ is recorded in the table CHILD_PARENT by using the generated CHILD_ID field values in table CHILD and PERSON_ID field values in table PERSON.
The database objects are closed and connection is terminated.
Source Code
To view the source code for the DerbyDataAdaptor sample, refer to examples/interview-engine/data-adaptor in the Java runtime zip file.